Amazon Transcribe のカスタム語彙 (Custom Vocabularies) を日本語で作成する時にハマったこと

コンバンハ、千葉（幸）です。

語彙、足りてますか？

人間の語彙を増やすには勉強するしかありませんが、Amazon Transcribe の語彙はカスタム語彙として増やすことができます。

日本語のカスタム語彙を作成する時に文字コードや改行コードまわりで少しハマりましたので、備忘として記しておきます。

目次

• 目次
• カスタム語彙（Custom Vocabularies）とは
• カスタム語彙用のテキストファイルの作成
  • リスト形式
  • テーブル形式
• カスタム語彙の作成
• 文字コードと改行コードによる Validation error
• 終わりに

カスタム語彙（Custom Vocabularies）とは

AWSドキュメント

カスタム語彙とは、 Amazon Transcribe による文字起こしの精度を高めるために使用できるオプション機能です。辞書に載っていない言葉などシステムが認識するのが難しい言葉に対して、発音や表示形式を定義したリストを予め渡しておくことによって、より自然な文字起こし結果を得ることができます。

Amazon Transcribe による文字起こしはバッチ文字起こしとリアルタイム文字起こしの2種類がありますが、どちらもカスタム語彙に対応しています。（ただし、リアルタイム文字起こしは対応している言語が限定されています。日本語には対応していません。）

日本語のカスタム語彙を使用している例としては、以下の記事が分かりやすかったです。

カスタム語彙用のテキストファイルの作成

カスタム語彙の作成のためにインプット用のテキストファイルを作成する必要があります。テキストファイルの形式には以下2種類があります。

• リスト形式
• テーブル形式

リスト形式

リスト形式は、単語もしくはフレーズを、改行ないしカンマで区切って羅列して作成します。

前者の例は以下の通りです。

Los-Angeles
F.B.I.
Etienne

後者の例は以下です。

Los-Angeles,F.B.I.,Etienne

テーブル形式

テーブル形式は、以下の4つのフィールドを持ちます。

• Phrase（句、フレーズ）:
  • 認識する必要がある単語もしくはフレーズ。指定が必須
• IPA（International Phonetic Alphabet、国際音声記号）:
  • 音声記号を用いて発音を指定することができる
  • SoundsLikeフィールドと併用はできない
• SoundsLike :
  • 単語やフレーズを分割して発音を指定できる
  • IPAフィールドと併用はできない
• DisplayAs :
  • 単語やフレーズを文字に出力する時の表示を定義できる
  • 省略した場合、Phraseフィールドの内容が採用される

前述のリスト形式においては、Phraseフィールド相当の情報のみを指定していることになります。テーブル形式においては、発音や表示についても情報を追加することができます。

テーブル形式を用いたテキストファイルの例は以下です。

Phrase     [TAB]IPA       [TAB]SoundsLike[TAB]DisplayAs
Los-Angeles[TAB]          [TAB]          [TAB]Los Angeles
F.B.I.     [TAB]ɛ f b i aɪ[TAB]          [TAB]FBI
Etienne    [TAB]          [TAB]eh-tee-en [TAB]

各フィールドはTAB文字によって区切る必要があります。また、フィールドの順番は任意です。

カスタム語彙の作成

テキストファイルが作成できたら、それを基にAWSリソースとしてのカスタム語彙を作成します。

リスト形式、テーブル形式問わず、テキストファイルには以下の制約があります。

• テキストファイルのサイズは50KBが上限
• テキストファイル内のエントリは256文字未満であること
• 使用文字セットのみが含まれていること

3番目について補足すると、日本語のカスタム語彙を作成したい場合には以下のような制約があります。

Character sets for custom vocabularies and vocabulary filters - Amazon Transcribe

• PhraseフィールドとDisplayAsでは以下の一覧に含まれている日本語の文字を使用できる
  • japanese-character-set.txt
  • （2023/2/21）以下に変わっていそうです
    • ja-jp-character-set.zip (GitHub)
    • https://docs.aws.amazon.com/transcribe/latest/dg/samples/ja-jp-character-set.zip
• SoundsLikeフィールドではローマ字が使用できる
• IPAフィールドには国際音声記号が使用できる

言語によって各フィールドで使用できる文字セットが異なりますので注意してください。

マネジメントコンソールからカスタム語彙を作成する際の画面イメージは以下です。

カスタム語彙の名前と言語を指定し、テキストファイルをインプットとして引き渡します。以下の2パターンでテキストファイルを指定できます。

• Amazon Transcribe のコンソールからアップロード
  • リスト形式のテキストファイルにのみ対応
• 予めS3バケットにファイルをアップロードし、ロケーション指定
  • リスト形式およびテーブル形式のテキストファイルに対応

前者の方式でテーブル形式のテキストファイルを指定した場合、カスタム語彙の作成に失敗するので注意が必要です。

失敗した際のイメージは以下です。

Failure reasonとして以下が表示されます、

The vocabulary that you’re trying to create contains invalid characters or incorrectly formatted terms. See the developer guide for more information.

ちなみに、テキストファイルの言語とカスタム語彙の言語が一致していない（つまりは使用文字セットに則っていない）場合にも同様のメッセージが表示されました。今回の例で言えば、日本語用にテキストファイルを作っていたものの、カスタム語彙作成時の言語として English を選択してしまった場合などが該当します。

文字コードと改行コードによる Validation error

上記で確認したような制約をクリアした上でもなお、カスタム語彙の作成に失敗するケースがありました。

Failure reason は先ほどと異なり以下のようになります。

Validation error: Vocabulary file format does not comply with requirements. Check documentation on how to format valid vocabulary file.

試行錯誤する中でどうやら文字コードと改行コードまわりが関係していそうだということがわかったので、いくつかの組み合わせで試してみることにします。

我らがサクラエディタを利用して、複数の組み合わせを作ります。

ちなみにここでの「CP」はコードページのことで、チェックを入れることでより多くの文字コードが指定できるようです。（今回は見送りました。）

また、「BOM」は byte order mark の略で、符号化の判別に使われるデータです。以下のサイトが分かりやすかったです。

改行コードについては、以下の記事が参考になりました。

今回は以下の組み合わせで9つのファイルを作成しました。

• 文字コード
  • Shift_JIS
  • UTF-8
  • UTF-8（BOMあり）
• 改行コード
  • CR（\r）
  • CRLF（\r\n）
  • LF（\n）

それぞれを用いてカスタム語彙の作成を試みたところ、以下のような結果になりました。

	CR	CRLF	LF
Shift_JIS	失敗	失敗	失敗
UTF-8	失敗	成功	成功
UTF-8（BOMあり）	失敗	失敗	失敗

これらの仕様についてドキュメントに記述がないか確認してみたのですが、ドンピシャのものは見つけられませんでした。

文字コードについては、以下の記述が該当しているのかもしれません。

You can use any UTF-8 character in the DisplayAs field.

改行コードについては、同一に扱って良いものなのか不明ですが、 Amazon Transcribe Medical におけるカスタム語彙で以下の記述がありました。

医学用語のカスタム語彙

Windows でテキストファイルを編集する場合、ファイルが CRLF 形式ではなく LF 形式であることを確認してください。

ひとまず、UTF-8 で LF（\n）に統一した方が変にハマることがなくてよいように思いました。

終わりに

Amazon Transcribe のカスタム語彙におけるハマりポイントでした。文字コードや改行コードについて普段あまり意識することがなかったので、よいきっかけとなりました。同じようなケースに陥った方の参考になれば幸いです。

ドキュメントに詳細な仕様を書いてくれたり、具体的にどこが誤っているかまでメッセージに出力してくれるととても助かるので、アップデートに期待です。あとは人間の脳にもAPI経由で語彙を追加できるようなアップデートも期待しています。よろしくお願いします。